AniNIX/Wiki
3
0
Fork 0
Code Issues 9 Pull Requests 3 Releases Activity

Major documentation rework -- Entities and Ubiqtorate still need cleanup.

Browse Source
This commit is contained in:
DarkFeather
2020-10-09 04:19:07 -05:00
parent f506025c54
commit a118037532
76 changed files with 1011 additions and 1246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
Policies/Design_Principles.md Normal file
View File

@@ -0,0 +1,75 @@
The AniNIX is not a collection of one-offs. The following considerations should be evaluated before testing or releasing a new project, and quality assurance should report if any of these design principles aren't met.
# Meeting the need
Any design should be evaluated against the need it is intended to meet. Ask the following questions:
* Does an existing package fulfill the need better than custom development by the AniNIX? [TheRaven](/AniNIX/TheRaven) is a fairly specialized package, but [Yggdrasil](../Services/Yggdrasil.md) was superior to our self-written Siren and an externally-maintained package, which saves the network human hours.
* Is the implementation going to fit the state of the industry? This is a slightly nebulous question, but Bazaar was deprecated in favor of Git for the Foundation project because Git is more widely used and better supported. Following the state of the industry usually means superior features, testing, support, and adoption.
* Will filling this need justify the resource expenditure?
* Will end users adopt this solution and fill their need that way, or will the effort be wasted when a more professional solution will be released and adopted later?
# Security-First Design
## Remote Access vs. Local Only
Remote access isn't needed in all cases and opens the network to vulnerabilities. The CryptoWorkbench in the Foundation doesn't need to be remotely accessible when users can deploy their own with git; the Foundation itself doesn't need to allow the world to write to it to allow cooperation. These kinds of projects, that are either read-only or non-deliverable, can be safely monitored with [filesystem intrusion detection](../Services/Cerberus.md), virus scanning, and existing controls over remote access to the host.
[SSH](../Services/SSH.md) and [IRC](../Services/IRC.md) do allow remote access, and require additional safeguards to those above. Network intrusion detection becomes a need, since this is a means by which attackers can exploit a service. Firewall rules will need to be opened and monitored.
## Penetration Testing Planning Before Release
Identify a plan and set aside resources to test the project before release. Failed attempts at open chroot accounts on [Core](../Entities/Core.md) have been identified and shut down before being generally released; these kinds of attempts allow the AniNIX to have confidence in the released projects while not stifling the developer's ideas. Failed ideas that are insufficiently secured are a good exercise in development, and they can be tabled for later when better controls or designs are available.
## Appropriate User Rights
Running services as root is generally a bad idea for non-security services. Make sure to have a unprivileged account for any other service, particularly if they allow remote access.
## Physical Access
The AniNIX does not believe in the cloud (or, as it is affectionately known, Computers Living On Unknown Datacenters). Cloud computing centralizes storage in a place that is difficult if not impossible for end users to secure and protect; particularly for sensitive information like social security numbers, this is not acceptable. Redundancy of the cloud is also very expensive and hard for small groups to achieve.
In contrast, if any given user can replicate shared data from the AniNIX and each other on storage that they monitor and secure, the network becomes harder to destroy, impede, or rob. This decentralized model ensures that users know where their data lives, and any given user can stand up the network.
For services that are hosting information like passwords, the device should be physically secured and the storage encrypted. While they can be made useless by destruction, this should prevent physical access resulting in an immediate compromise.
## Privacy
Guarantees of privacy are a major concern in designs. The AniNIX needs to be able to protect itself while doing its best to provide the same right to others. This ties in with concerns of Remote Access -- remote access that isn't by read-only transport requires an account which can be paired with an individual. This should be used for collaboration with the network and for maintaining user preferences.
However, tools like documentation and source code should be available from behind privacy tools and without identifying a user. When governments can outlaw information, as many repressive regimes in the Middle East and elsewhere have done, the AniNIX seeks to make sure that the peopke still have power by information.
Furthermore, any communication across a wwider network should be encrypted. [WebServer](../Services/WebServer.md) controls most of this via the Let's Encrypt SSL certificate for the web apps, but SSH also encrypts its communication. Unencrypted communication is insecure and not private by default and should be prohibited as much as possible.
# End User Experience
Services developed in isolation are interesting exercises, but in the end it is the user's comfort and trust in the service that will keep it being used.
## Reliability and Stability
Physical devices should have redundant components and power sources as much as possible. Protections against failures in services, such as frequently saving state and quickly restarting after a failure, are highly encouraged.
Projects should crash rarely if ever -- any crash should be investigated immediately and the relevant code revisited. Frequent crashes are perhaps the highest cause of end-user dissatisfaction.
## Performance
Performance is second only to stability in terms of the end-user experience. Services should be fast and light to meet the needs of users -- the state of development today doesn't tolerate slow and/or intensive processes for all but the most critical projects.
Ensure that memory is allocated only when needed and deallocated as soon as possible. Processing should use efficient algorithms to meet the goal and should be open to re-evaluation. Network should minimize the use of images in transport -- X11 forwarding and video streaming should only be used in services that the user expects to be noncritical and potentially slow.
## Graphical Design
[Minimalism](https://en.wikipedia.org/wiki/Minimalism) is a key principle in the AniNIX design. An uncluttered interface with simple, intuitive options reduce the barrier to entry and improve adoption.
The AniNIX, as you can see by this page, follows a white-on-black color scheme with red for important or interactive elements. White-on-black results in less light emission from screens, and in low-light conditions this means less effect on the night vision. [A study in August 2013](http://www.jneurosci.org/content/33/32/13081.full) found that white and blue light were the most disruptive to the animal test subjects, while red light was the least. [A LensCrafters study](https://www.lenscrafters.com/lc-us/vision-guide/blue-light-computer-eye-strain?j=2179694&sfmc_sub=150010356&l=175_HTML&u=101219824&mid=6010051&jb=5345&cid=EC-2179694-5/14/2017&&smtrctid=150010356) also found blue disruptive. Red accents, therefore, offer the least disruption while keeping readable text with the highest contrast. The three-color scheme further assists the colorblind, who should still be able to clearly identify the static and interactive elements on the interface.
GUI elements will generally be deployed by a Web page, as this is a cross-platform means of providing access and easy to code. Should packages choose to include a local GUI, they are responsible for meeting these principles with a best-effort approach.
## Mobile Access Design
With the rise of the smartphone, remotely accessible services should offer a simple means via some app to reduce network traffic. The app interface should be intuitive and quick to use.
## Etymology
The AniNIX attaches a unique name, such as Sora for OpenLDAP or Yggdrasil for Emby, to packages and services it instantiates. The reason for this is that the name defines a scope of functionality the AniNIX expects to rely on -- should the underlying package change, such as replacing Plex Media Server with Emby, documenation and AniNIX packages will use the same name.
Names given should be chosen for relevance to the function being provided (Singularity being a pull service, Foundation being the basis on which we're built, etc.) and for ease of memory. Only the most basic services, such as IRC, WebServer, and SSH, will be left unnamed.
These names are not intended to supercede the licensing or attribution of other packages -- applications, once installed, should only update the minimal allowable elements to be usable under AniNIX principles. Whereever possible, this should be done via the application's provided interface, such as enabling dark modes. We also should not remove any links that the application provides to its own documentation, licensing, or websites. This means that AniNIX etymology only applies to administrators and is otherwise invisible to end users.
# Maintainability
Make sure that a project can be easily maintained. This means following the Development Best Practices and submitting Markdown documentation for the project.
Ensure that projects are configurable for key elements, particularly for things like passwords that change often, and they should use well-known and understood languages per the Development Best Practices.

154
Policies/Development_Best_Practices.md Normal file
View File

@@ -0,0 +1,154 @@
Like all organizations, the AniNIX has a set of coding and development best practices. See [HelloWorld](/AniNIX/HelloWorld) for an example project that should implement these recommendations and provide a skeleton to use.
# Packages
Each package should have a single, dedicated purpose. Developers should be careful against scope creep -- if additional functionality is needed beyond the purpose of the package, another package should be created to fill the need.
## Commenting
All source files should be commented with at least one descriptive comment per operational unit. Ideally, there will be no more than 20 lines between comments, unless so dictated by function. Block comments should be at the beginning of functions summarizing the work the function does, the parameters if any, and the return value if any.
```
/// <summary>
/// Put the summary here
/// </summary>
/// <param name="xname">A parameter for X</param>
/// <param name="yname">A parameter for Y</param>
/// <returns>The return value</returns>
```
Source files should also maintain a header block tracking ownership and scope. Some source systems will also require dependency and versioning information in this block. This information is optional; the AniNIX deploys by rolling release, so the PKGBUILD installed into pacman or the Git source repo will have the version. Makefiles and PKGBUILDS will also track dependencies.
```
/*
* File:
*
* Description:
*
* Package:
* Copyright:
*
* Author:
*/
```
Avoid so-called "code-golfing" in source-code -- source should be easy to read, consistent, and verbose. Comments and other space-consuming elements can be stripped out in compilation for space-conscious projects.
## Safe Coding
All inputs should be sanitized to match the developer's expectations during operations. Unlimited reads are unacceptable -- bound the reads with a buffer to contain the memory pressure to a reasonable space and to prevent overflows.
All memory that is allocated should be deallocated before the process exits -- zeroing the memory segment is optional.
## Portability
Packages should be reasonably portable to other systems, but there is no expectation of unlimited portability. The network should generally test against ArchLinux -- portable projects should also strive to test against CentOS, Kali Linux, and Windows.
## External Standards
AniNIX projects should follow international standards to ease user interaction.
* [Standard keyboard shortcuts](http://en.wikipedia.org/wiki/Table_of_keyboard_shortcuts)
* [Android](https://developer.android.com/guide/practices/ui_guidelines/index.html) and [Google Web](https://support.google.com/webmasters/answer/35769#1) principles
* [Standard command-line options](http://www.tldp.org/LDP/abs/html/standard-options.html)
## Version Control
[Git](../Services/Foundation.md) is the version-control mechanism of choice. Packages being developed by Core admins should be added as a folder immediately under the foundation folder on checkout. Commit messages should be specific, and changes should be attempted in a development branch before being merged to master.
## Makefiles
All packages should include a Makefile with at least the following rules.
* compile: This should include all the steps necessary to compile the package. When this is done, the final executable should be able to run from the same directory as the Makefile.
* install: This should include all the steps necessary to installed the compiled files to the OS and set appropriate permissions. The compile step should be a dependency.
* uninstall: the reverse steps from install
* clean: This should remove any files built by compile.
* test: this should include the rules needed to run the package without installing.
* diff: this should compare local build with installed executables or scripts.
* reverse: this should pull the installed copies of scripts back to the source directory
* checkperm: make sure permissions are set.
Here's a skeleton Makefile to use.
```
pkgdirname != basename `git config remote.origin.url` | sed 's/.git$$//'
compile:
install: compile
uninstall:
test: compile
python3 -m pytest
clean:
@bash -c 'printf "This will reset the repository and lose all work. Confirm? [YES/no] " ; read answer; [ "$$answer" == "YES" ] && exit 0; exit 1'
cat .gitignore | xargs rm -Rf
diff:
reverse:
checkperm:
```
## PKGBUILD
Standalone packages like [CryptoWorkbench](/AniNIX/CryptoWorkbench) should include a PKGBUILD for the ArchLinux package manager.
## Language
Filenames should indicate language using standard extensions.
### bash
All OS scripts should be written in bash and include /bin/bash as a dependency.
* We don't use CSH/TCSH for [reasons](http://www.grymoire.com/Unix/Csh.html#uh-0).
* KSH has other problems.
* ZSH is being considered but presently has too low an adoption rate.
* Old-school SH is missing features.
[A style guide](http://www.daveeddy.com/bash/) is available.
### HTML/CSS/PHP
All Web sites should be written in HTML with minimal inline CSS -- a proper stylesheet should be included.
* For web pages expected to compile from server execution, PHP should be the chosen language. We have not been able to convert to Facebook's HHVM yet.
* For web pages expected to execute functions on the client browser, Javascript should be the chosen language and the Javascript should live in script file.
### C
Low-level applications should be written in C and require /usr/bin/gcc as a dependency. Re-useable functions should be written in linked libraries.
See man pages for documentation.
### C#
All large-scale applications should be written in C# and include the /usr/bin/mono and /usr/bin/mcs dependencies on compile. C# has been evaluated to be an industry-standard and portable language with a lesser exploit history, superior typing, and better resource management than Java.
[Documentation](https://docs.microsoft.com/en-us/dotnet/csharp/index) is available.
### Python3
QA and proof-of-concept code should be written in Python3 -- this is a standard among ethical hacking classes, and the programming python3/pdb interfaces make writing code easy.
[Documentation](https://docs.python.org/3.7/) is available.
## Integration
* Services that do not need to run as a privileged user (notably Cerberus' main HIDS and Heartbeat) should deprivilege.
```
1. Hook for depriviliging
if ! getent passwd raven; then useradd -M -G git,ircd,api -d ${CONFDIR} raven; fi
```
Configuration and installed files should go to the following locations:
* Configuration should go into /usr/local/etc/PackageName/
* Direct executables should go into /usr/local/bin
* Indirect executables, such as compiled Mono projects, should go into /opt/aninix/PackageName/
* Logfiles should default to /var/log/PackageName/
## Code Reuse
All projects should seek to maximize code re-use. Any source code that could be generalized should go into [Uniglot](/AniNIX/Uniglot). This repository should be included a dependency in PKGBUILDS and checked by Makefiles.
## OS Integration
# Process
## Design
Projects should be designed with an established scope. This scope should be outlined in the package README.md. The appropriate language should be selected.
## Development
Initial development should be done to get the package in a working condition following the above requirements. The appropriate README.md should be updated with development notes, dependencies, and a wishlist as development proceeds.
## Peer QA
If working with a group or any available peers, these peers should read through the code. Comments should be submitted in Gitea issues or pull requests -- quick conversation can be had on IRC until all is sorted. Until all peer comments are handled to the group's satisfaction, the process will hang.
## QA
All packages should be tested automatically and manually before being released. This should include unit tests for functionality, sanitizing inputs, stability, etc.
## Release
Release via Foundation and preferably also [Maat](https://maat.aninix.net). Web view is provided by AniNIX Foundation, and git cloning programs are available for all major distributions.
## Bug Reporting and Fixing
Bugs should be announced to the network staff via the IRC system. If the bug is geniune, an issue should be created and published to track the resolution. Bug fixes should trump new enhancements and specific fixes tracked as pull requests.

46
Policies/User_Ethics.md Normal file
View File

@@ -0,0 +1,46 @@
AniNIX users should follow good ethical principles when using the network. AniNIX resources should be used in accordance with these principles -- activity outside the network is not ours to dictate.
# Our Mission Statement
The mission statement of the AniNIX is simple:
1. Provide an example suite of services and serve a small userbase
1. Provide documentation and source code to allow anyone to replicate the system.
1. Contribute actively to the global community by involvement in the open-source community and charity work.
# Open Source
[Open-source][1] means that are willing to provide access to as much information as possible, sharing our experience, work, and assets with the world. (We cannot disclose security tokens and other privileged information for our own self-preservation.) We intend for anyone to take the AniNIX model and inspect it, modify, or enhance it by looking at our documentation and source code. We believe this yields the benefits of control, training, security, and stability to our users, as the more people inspect something the fewer errors are likely to be present.
# The Hacker Ethic
When you give people the means to be creative for themselves and to share their work, they can create beautiful communities of industry and passion. With proper moderation against malice, the human collective evolves, and the AniNIX seeks to include this.
The AniNIX subscribes to the [Hacker Ethic][2] and should build itself to support the same. In order, these are the ideals development in the AniNIX should encourage:
* _World improvement_: The world is not a friendly place to your average person. Compute power can be leveraged to improving people's lives, not just in the pursuit of personal power or profit at the expense of others. Projects within the AniNIX should serve the betterment of the wider world in some fashion or at least some portion of the userbase. We do not use our resources to profiteer from others, particularly their lack of access.
* _Openness and sharing, particularly open-source_: We are world citizens, with equal human rights. Sharing, collaboration, and openness improve the lives of everyone and let us grow as a planet. AniNIX projects and source should be openly available; security keys and credentials may be obfuscated to protect the network.
* _Decentralization_: True democracy is the voice of the people -- the rule of the majority. Too much centralization results in an easy target that can be destroyed by those seeking their own power and profit and to silence opposition. When everyone in the masses has a voice that can't be silenced, they carry immense weight for revolutionizing and improving life.
* _Equal, free access to computing_: The Internet is the last bastion of human free speech and stream-of-consciousness, and open access for everyone gives everyone a voice. Computers allow free educational materials and community-building, and learning to use them promotes intellectualism and self-education. No one should be barred based on race, gender identity, gender expression, sexual orientation, ability, age, cultural identity, IQ, religion, socioeconomic status, etc. -- the sole grounds for blocking access is to prevent specific, malicious actions, such as identity theft, human trafficking, etc.
## AniNIX Application
* The AniNIX provides a number of free-to-access offerings in the interest of giving back and we support a number of charitable organizations for the aim of world improvement.
* We actively fold for [Folding@Home](https://stats.foldingathome.org/team/250807).
* We support [DAREBEE](https://darebee.com).
* We support [Wikipedia](https://wikipedia.org).
* The [AniNIX/Foundation](https://foundation.aninix.net) offers all the documentation and code necessary to replicate AniNIX services.
* The AniNIX makes as many of its applications Web-accessible and offline-accessible as possible to reduce the barrier to entry -- even a public library terminal should have sufficient resources.
# Good-faith Contributions
All contributions to the AniNIX should be done in good faith -- users will not be punished for bad work submitted in an honest fashion. However, in the interest of promoting good faith, they should also be respectful of criticism and advice on how to improve their work. The AniNIX seeks to improve steadily and welcomes debate and discussion.
If you have concerns or suggestions, please use the talk page of a topic to discuss them.
# Respect to Peers
Please respect your peers in all communication. The AniNIX administrators reserve the right to terminate services at any time to any user found to be disruptive or damaging to the network. We seek a collaborative, not elitist, environment, and all viewpoints should be welcome in a debate.
# Handling of Malware
The AniNIX, being security-minded, handles malware. Please make sure you only transfer malware in secured, inert formats to other users and clearly label it as such so that they know to analyze it.
The use of malware to attack, harm, or malign the network will not be tolerated. Ensure all testing is done in isolated networks with protected machines to prevent accidental assaults.
Be sure to read [18 US Code 1030](https://www.law.cornell.edu/uscode/text/18/1030) (thanks to Cornell for providing a copy), particularly section a5A, before distributing or publishing malware source.
<!-- References -->
[1]: https://opensource.com/open-source-way "OpenSource.com"
[2]: https://en.wikipedia.org/wiki/Hacker_ethic "Wikipedia"